home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / Development / vbcc / doc / vlink.doc < prev    next >
Encoding:
Text File  |  2002-10-27  |  9.4 KB  |  224 lines
  1. vlink V0.8        VBCC ANSI C Compiler Reference Manual           vlink V0.8
  2.  
  3. NAME
  4.      vlink - linker for multiple file formats
  5.  
  6. SYNOPSIS
  7.      vlink [-dhrstvwxMRSX] [-B linkmode] [-b targetname] [-baseoff offset]
  8.            [-F filename] [-L library-search-path] [-l library-specifier]
  9.            [-multibase] [-nostdlib] [-o filename] [-sc] [-sd] [-T script]
  10.            [-V version] [-y symbol] input-files...
  11.  
  12. DESCRIPTION
  13.      vlink combines the object and archive files given on the command line
  14.      into a new object file. The output object file is either an executable
  15.      program, a shared object suitable for loading at run-time, or an
  16.      object file that can once again be processed by vlink. Object files
  17.      and archives are processed in the order given on the command line.
  18.  
  19.      The file format of an input object file is determined automatically
  20.      by vlink. The default output file format is compiled in (see -v)
  21.      and may be changed by -b.
  22.  
  23.      Supported file formats:
  24.  
  25.      amigaos
  26.              The AmigaDos hunk format for M68k. Requires AmigaOS 2.04.
  27.              No shared objects. Small data offset: 0x7ffe. Linker
  28.              symbols: _DATA_BAS_, _DATA_LEN_, _BSS_LEN_ (PhxAss),
  29.              _LinkerDB, __BSSBAS, __BSSLEN (SASC/StormC), __DATA_BAS,
  30.              __DATA_LEN, __BSS_LEN, __RESIDENT (DICE-C), ___machtype,
  31.              ___text_size, ___data_size, ___bss_size (GNU-gcc).
  32.              Automatic constructor/destructor function tables: __ctors,
  33.              __dtors.
  34.  
  35.      amigaehf
  36.              An extension of the AmigaDOS hunk format for the PowerPC,
  37.              32-bit, big endian, as introduced by Haage&Partner GmbH. No
  38.              executables (they are in amigaos format) or shared objects.
  39.              The same linker symbols, constructors/destructors as under
  40.              amigaos are supported. Additionally, "@_name" symbols will
  41.              be created on demand (when referenced).
  42.  
  43.      elf32ppcbe
  44.              ELF (executable linkable format) for PowerPC, 32-bit,
  45.              big endian. Small data offset: 0x7ff0. Linker symbols:
  46.              _SDA_BASE_ and _SDA2_BASE (EABI only). Automatic construc-
  47.              tor/destructor function tables will be placed into the
  48.              sections .ctors and .dtors.
  49.  
  50.      elf32powerup
  51.              ELF PowerPC 32-bit big endian for the PowerUp turbo boards
  52.              from Phase5. Main difference to elf32ppcbe is the format
  53.              of the executable (which is a relocatable object) and a new
  54.              linker symbol, _LinkerDB, for vbccppc-compatibility.
  55.  
  56.      a.out
  57.              Currently supported: aoutbsd68k (NetBSD/68k), aoutbsd68k4k
  58.              (NetBSD/68k 4K page size), aoutsun010 (SunOS 68010 and
  59.              AmigaOS 68000/010), aoutsun020 (SunOS 68020 and AmigaOS
  60.              68020-68060).
  61.              Small data offset: 0x7ff0 (unused). Linker symbols:
  62.              _etext, _edata, _end, __GLOBAL_OFFSET_TABLE_,
  63.              __PROCEDURE_LINKAGE_TABLE_, __DYNAMIC.
  64.  
  65.      rawbin1
  66.              Absolute raw binary file. The sections and base addresses
  67.              have to be specified by a linker script (option -T). Gaps
  68.              between sections are filled with 0-bytes. Without a linker
  69.              script, the raw binary will be relocated to base address 0.
  70.  
  71.      rawbin2
  72.              Like rawbin1. The only difference is, that a separate file
  73.              will be created for every section. The file name will get
  74.              the section's base address appended.
  75.  
  76.      srec19, srec28, srec37
  77.              Motorola S-Record format. No symbols. Output format only.
  78.              Without a linker script, the raw binary will be relocated
  79.              to base address 0.
  80.  
  81.  
  82.      The options are as follows:
  83.  
  84.      -Bdynamic
  85.              Specifies that linking against dynamic libraries can take
  86.              place. If a library specifier of the form -lx appears on
  87.              the command line, ld searches for a library of the from
  88.              libx.so.n.m (see the -l option) according to the search
  89.              rules in effect. If such a file can not be found a tradi-
  90.              tional archive is looked for. This options can appear
  91.              anywhere on the command line and is complementary to -Bstatic.
  92.  
  93.      -Bstatic
  94.              The counterpart of -Bdynamic. This option turns off dynamic
  95.              linking for all library specifiers until a -Bdynamic is once
  96.              again given. Any explicitly mentioned shared object encoun-
  97.              tered on the command line while this option is in effect is
  98.              flagged as an error.
  99.  
  100.      -Bshareable
  101.              Instructs the linker to build a shared object from the object
  102.              files rather than a normal executable image.
  103.  
  104.      -Bsymbolic
  105.              This option causes all symbolic references in the output to be
  106.              resolved in this link-edit session. The only remaining run-
  107.              time relocation requirements are base-relative relocations,
  108.              ie. translation with respect to the load address. Failure to
  109.              resolve any symbolic reference causes an error to be reported.
  110.  
  111.      -Bforcearchive
  112.              Force all members of archives to be loaded, whether or not such
  113.              members contribute a definition to any plain object files.
  114.              Useful for making a shared library from an archive of PIC
  115.              objects without having to unpack the archive.
  116.  
  117.      -b targetname
  118.              Specifies target file format for the output file. See
  119.              also "Supported file formats".
  120.  
  121.      -baseoff offset
  122.              Defines section offset for base-relative relocations. The
  123.              default offset is target-dependant (e.g. 0x7ffe for amigaos
  124.              and 0x7ff0 for elf32ppcbe).
  125.  
  126.      -dc     Force allocation of commons even when producing relocatable
  127.              output.
  128.  
  129.      -dn     Same as: -Bstatic
  130.  
  131.      -dy     Same as: -Bdynamic
  132.  
  133.      -F filename
  134.              A list of object file names is read from the specified file.
  135.              Useful, if the number of objects exceeds the length of the
  136.              command line.
  137.  
  138.      -h      Prints a short help text.
  139.  
  140.      -L library-search-path
  141.              Add path to the list of directories to search for libraries
  142.              specified with the -l option. When a default search path
  143.              was compiled in (see -v), then it is searched last.
  144.  
  145.      -l library-specifier
  146.              This option specifies a library to be considered for inclusion
  147.              in the output. If the -Bdynamic option is in effect, a shared
  148.              library of the form lib<spec>.so.m.n (where m is the major,
  149.              and n is the minor version number, respectively) is searched
  150.              for first. The library with the highest version found in the
  151.              search path is selected. If no shared library is found or
  152.              the -Bstatic option is in effect, an archive of the form
  153.              lib<spec>.a is looked for in the library search path.
  154.              For amigaos/amigaehf file formats, the libraries are called
  155.  
  156.      -M      Produce output about the mapping of segments of the input
  157.              files and the values assigned to symbols in the output file.
  158.  
  159.      -multibase
  160.              The default behaviour of vlink is to merge all sections
  161.              which are accessed base-relative. This guarantees a single
  162.              small data section, which can be accessed through a base
  163.              register.
  164.              If this is not desired - maybe you have several base re-
  165.              gisters and small data sections - you can disable this
  166.              behavoiur by specifying -multibase. 
  167.  
  168.      -nostdlib
  169.              Ignore default library search path, if one was compiled in.
  170.  
  171.      -o filename
  172.              Specifies the name of the output file. Defaults to "a.out".
  173.  
  174.      -R      If the target file format supports it, use the short
  175.              format for relocations.
  176.  
  177.      -r      Produce relocatable object file, suitable for another
  178.              linker pass.
  179.  
  180.      -S      Strip all debugger symbols from the output.
  181.  
  182.      -s      Strip all symbols from the output.
  183.  
  184.      -sc     Merge all code sections to a single code section.
  185.  
  186.      -sd     Merge all data and bss sections to a single data-bss section.
  187.  
  188.      -T script
  189.              Specifies a linker script, which defines the absolute
  190.              locations for every section. The syntax is similar to
  191.              that used in GNU linker scripts, but still very limited.
  192.  
  193.      -t      Trace the linker's file accesses.
  194.  
  195.      -V version
  196.              Minimum major version of shared object to be linked.
  197.  
  198.      -v      Prints vlink version string, default library search path
  199.              and implemented target file formats.
  200.  
  201.      -w      Suppress all warning messages.
  202.  
  203.      -X      Discard local symbols in the input files that start with the
  204.              letter "L" or with a dot.
  205.  
  206.      -x      Discard all local symbols in the input files.
  207.  
  208.      -y symbol
  209.              Trace the manipulations inflicted on symbol.
  210.  
  211. BUGS
  212.      Target elf32ppcbe can't generate shared objects or executables.
  213.      Target elf32powerup can't generate shared objects.
  214.      Writing objects, shared objects or executables in a.out format is
  215.      currently not supported.
  216.      The following options are not really supported: -B, -dn, -dy, -S, -X.
  217.      Option -R for ELF is untested and should be avoided (works fine
  218.      for AmigaOS hunk format though).
  219.      Real debugger support (source level debugging, etc.) is still
  220.      missing for all target file formats.
  221.  
  222.  
  223. Frank Wille                  16-Feb-2001                frank@phoenix.owl.de
  224.